Для работы с интернет-магазинами пользователей, мы разработали Push API. Главное отличие от простого REST API в том, что вместо того, чтобы приложение (сайт) клиента делал постоянные запросы к серверам СмартЛомбард, делаются запросы самим сервисом СмартЛомбард на сервера (сайты) клиентов.
При любом добавлении, изменении или удалении товара в комиссионном магазине происходит событие, которое отправляется посредством HTTP запроса на сайт клиента. Клиент на своем сайте реализует обработку таких запросов, и реализует добавление, изменение и удаления товаров.
Рекомендуем приходящие сообщения и информацию о сущностях идентифицировать по уникальным id, которые мы отправляем, для мерчантов это - workplace, а для товаров - article.
Настоятельно рекомендуем следить за дублированием этих ID.
Сущность “Магазин” - содержит в себе данные филиала (рабочего места в терминологии smartlombard).
Типы генерируемых событий:
add - добавление мерчантаedit - редактирование мерчантаremove - удаление мерчантаworkplaceПримеры (json)
[
{
"type": "add",
"data": {
"workplace": 1,
"city": "Москва",
"name": "Тестовый ломбард",
"address": "Тестовый адрес",
"phone": "Тестовый телефон",
"image": [],
"description": "Описание работы филиала"
}
},
{
"type": "edit",
"data": {
"workplace": 1,
"city": "Москва",
"name": "Тестовый ломбард",
"address": "Тестовый адрес",
"phone": "Тестовый телефон",
"image": {
"src": "https://...",
"preview": "https://..."
},
"description": ""
}
},
{
"type": "remove",
"data": {
"workplace": 1
}
}
]
Поля
workplace - id филиалаshortlink - короткая ссылкаcity - городname - наименование филиалаaddress - адресphone - телефонimage - логотипdescription - описание филиала (настраивается в программе)Сущность “Товар” - содержит в себе данные о товаре.
ВАЖНО
В выгрузку не попадает лом ювелирных изделий.
Имущество выгружается только в статусе "На реализации"
Типы генерируемых событий:
add - добавление товараedit - редактирование товараremove - удаление товараПримеры (json)
[
{
"type": "add",
"item_type": 1,
"data": {
"organization": 1,
"workplace": 1,
"name": "Тестовый товар",
"article": 1,
"price": 1000,
"size": "",
"date": "24.05.2016 20:45",
"city": "Москва",
"features": "Тестовый товар, вес 5гр, 30mb памяти!",
"specifications": "4.3” LCD экран, носитель 30 MB, 20 часов работы",
"images": [
{
"src": "https://...",
"preview": "https://...",
"cover": 1
},
{
"src": "https://...",
"preview": "https://...",
"cover": 0
},
],
"category": "Тестовые товары",
"subcategory": "",
"metal_name": "",
"metal_standart_name": "",
"scrap_product": "",
"currency": "Руб."
}
},
{
"type": "edit",
"article": 1,
"item_type": 1,
"data": {
"workplace": 1,
"deleted": 1
}
},
{
"type": "remove",
"article": 1,
"item_type": 1
}
]
Поля
organization - id профиляworkplace - id филиалаname - Наименование товараarticle - id сущности (может совподать у имущества и товара)item_type - тип сущности (1- товар, 2- имущество)price - ценаsize - размер/длина (только для Ювелирных изделий)date - дата открытия объявленияcity - городfeatures - описание товараspecifications - характеристики товараimages - список изображений товараcategory - категорияsubcategory - подкатегорияmetal_name - наименование металла (только для Ювелирных изделий)metal_standart_name - наименование пробы (только для Ювелирных изделий)currency - обозначение валютыsold- флаг отвечающий за “продажу” товара, если = 1 тогда товар является проданнымwithdrawn - флаг отвечающий за списание или изъятие товара, если = 1 тогда товар является списанным/изъятымhidden - флаг позволяющий скрыть товар на сайте, если = 1 тогда товар является скрытымhidden_reason - причина сокрытия на витрине (применяется если флаг hidden = 1): 1 - товар на ремонте; 2 - товар зарезервирован; 3 - товар продан; 4 - товар изъят; 5 - товар на предпродажной подготовке;Все запросы мы отправляем в формате JSON, POST запросом, в кодировке UTF8.
Например:
[{
"data": {
"merchants": [
{
"type": "add",
"data": {
"workplace": 1,
"city": "Москва",
"name": "Тестовый ломбард",
"address": "Тестовый адресс",
"phone": "Тестовый телефон",
"image": [],
"description": "Тест описания"
}
},
{
"type": "edit",
"data": {
"workplace": 1,
"name": "Тестовый ломбард (отредактирован)",
"description": ""
}
},
{
"type": "remove",
"data": {
"workplace": 1
}
}]
}
}]
В основном СмартЛомбард шлет запросы где изменяется 1 сущность - товар. Но например, при включении магазина - отправляется информация обо всех товарах. Случается такое, что товаров слишком много и их целесообразно разделять на несколько порций для удобства отработки.
Поэтому мы отправляем данные группами по несколько сообщений в каждом и разделяя такие запросы по количеству товаров.
Для того, чтобы вы могли авторизовать запрос от нашей программы мы предоставляем каждому клиенту уникальный секретный ключ.
Его нужно хранить так, чтобы его никто не украл!
Также в каждом запросе мы отправляем хеш данных в http заголовке “AuthorizationSL”.
Таким образом проверить достоверность данных каждого запроса вы можете так (на примере PHP кода):
<?php
$secret = 'ВАШ СЕКРЕТНЫЙ КЛЮЧ';
$open_hash = $_SERVER['HTTP_AUTHORIZATIONSL'];
$data_hash = sha1(sha1($_POST['data']) . $secret);
if ($open_hash === $data_hash) {
// Авторизация пройдена
} else {
// Авторизация провалена
}
Вопрос — Для чего нужно подписывать данные ключом?
Ответ — Это нужно для авторизации запросов именно от нашей программы, чтобы злоумышленники не смогли подкинуть вам “левые” данные, или удалить старые.
Изображения приходят в ассоциативном массиве следующего вида:
[{
"src": "http: //storage.smartlombard.ru/1f/de/1fde4e31.jpg",
"preview": "http: //storage.smartlombard.ru/1f/de/1fde4e31.thumb.jpg",
"cover": 1
},
{
"src": "http: //storage.smartlombard.ru/1f/de/1fde4e31.jpg",
"preview": "http: //storage.smartlombard.ru/1f/de/1fde4e31.thumb.jpg",
"cover": 0
}]
ВАЖНО
Ссылка на изображение перестает работать после 3 обращений. Если вы планируете использовать картинки, то сохраняйте их к себе на сайт в момент создания или обновления товара. Смысл данного ограничения в снижении нагрузки на СмартЛомбард.
Предполагается, что от сайта клиента будут приходить ответы на каждый запрос, в определенном формате JSON.
Зачем посылать ответы на наши сообщения? В первую очередь для внутренних механизмов СмартЛомбарда, эти механизмы отвечают за хронологию запросов-ответов между СмартЛомбардом и вашими серверами (сайтами).
[{
"status": true,
"type": "good-add",
"unique": null,
"message": "Необязательное поле"
}, {
"status ": false,
"type": "merchant-remove",
"unique": 123
}]
status - успешен или нет запросtype - тип запроса, складывается из названия сущности и производимого действия, например, good-add - это добавление товара.unique - уникальный айди сущности над которой проводится операцияmessage - необязательное поле для вывода сообщенияauth - используется при ошибках в авторизацииmerchant-add - добавление нового магазинаmerchant-edit - редактирование магазинаmerchant-remove - удаление магазинаgood-add - для добавление товараgood-edit - редактирование товараgood-remove - удаление товараОбщий пример работы
Настоятельно не рекомендуем копировать этот код и использовать в продакшене, так как это пример, объясняющий общий принцип работы.
<?php
$secret = 'Ваш секретный ключ';
$open_hash = $_SERVER['HTTP_AUTHORIZATIONSL'];
$data_hash = sha1(sha1($_POST['data']) . $secret);
$messages = [];
// Проверяем подписаны ли данные ключом из СмартЛомбарда
if ($data_hash === $open_hash) {
$decoded = json_decode($_POST['data'], true);
// Проходимся по всем блокам
foreach ($decoded as $data) {
// Обозначаем переменные по которым доступны действия для сущностей
$merchants = $data['data']['merchants'];
$goods = $data['data']['goods'];
// Если существуют действия для мерчантов, выполняем их
if (count($merchants)) {
foreach ($merchants as $key => $merchantAction) {
// Если тип действия -- добавление мерчанта, добавим его в бд и в зависимости от обстоятельств выдадим сообщение
if ($merchantAction['type'] == 'add') {
// Добавляем товар в базу
$newMerchantId = 1;
// Тут должен быть ваш код
// Добавляем сообщение о том что добавили товар
$messages[] = [
'status' => true,
'type' => 'merchant-add',
'unique' => $newMerchantId,
'message' => 'Добавлен мерчант!'
];
}
// ...
}
}
// Если существуют действия для товаров, выполняем их
if (count($goods)) {
foreach ($goods as $key => $goodsAction) {
// Если тип действия -- добавление мерчанта, добавим его в бд и в зависимости от обстоятельств выдадим сообщение
if ($goodsAction['type'] == 'add') {
// ...
$newGoodId = 1;
// ...
$messages[] = [
'status' => true,
'type' => 'good-add',
'unique' => $newGoodId,
'message' => 'Товар добавлен!'
];
}
// Если другой тип действия разбираем его
if ($goodsAction['type'] == 'edit') {
// ...
$messages[] = [
'status' => true,
'type' => 'good-edit',
'message' => 'Товар отредактирован'
];
}
// ...
}
}
}
} else {
$messages[] = [
'status' => false,
'type' => 'auth',
'message' => 'Authorization failed'
];
}
if (count($messages)) {
echo json_encode($messages);
}
Запросы отправляются на url: https://online.smartlombard.ru/api/debt/get
Принимает следующие обязательные POST параметры:
client_surname - [строка] фамилия клиента, на которого оформлен залоговый билет/договор
(например: "Иванов")
number - [строка] номер залогового билета/договора
(например: "ВО000292")
organization - [число] номер(ID) организации (можно узнать в программе внизу страницы вида “номер_организации/номер_филиала”)
(например: 1)
workplace - [число] номер(ID) филиала (можно узнать в программе внизу страницы вида “номер_организации/номер_филиала”, либо в разделе Управление → Настройки → Филиалы)
(например: 4)
Примеры JSON ответа если есть ошибка:
{
"error": "Залоговый билет с таким номером не существует"
}
{
"error": "Залоговый билет с таким номером закрыт"
}
Пример JSON ответа если все хорошо:
{
"datetime": "15.01.2017 17:15",
"buyout_price": "1250 евро",
"buyout_date": "12.09.2019",
"price": "500 евро",
"summ": "750 евро",
"goods": ["Кольцо Золото 500 (12K) вес 10.00 гр.", "Texet"],
"online_prolongation_url": "https://online.smartlombard.ru/public/online_prolongation/?org_id=ORGANIZATION_ID&workplace_id=WORKPLACE_ID&token=TOKEN&number=PAWN_TICKET_NUMBER"
}
datetime - [строка] дата и время, на момент расчета задолженности. Отображается с учетом часового пояса филиала
(например: "15.01.2017 17:15")
buyout_price - [строка] сумма выкупа залогового билета
(например: "1250 евро")
ВНИМАНИЕ: может не указываться, если установлено свойство “Не передавать сумму займа на polombardam.shop и по Api” на странице Главная → Управление → Интернет-магазин
buyout_date - [строка] дата окончания основного срока залогового билета
(например: "12.09.2019")
price - [строка] сумма залога
(например: "500 евро")
ВНИМАНИЕ: может не указываться, если установлено свойство “Не передавать сумму займа на polombardam.shop и по Api” на странице Главная → Управление → Интернет-магазин
summ - [строка] сумма процентов при продлении
(например: "750 евро")
goods - [массив] перечень имуществ залогового билета
online_prolongation_url - [строка] ссылка для возможности онлайн продления. Вы можете отобразить эту ссылку пользователю, чтобы он перешел на страницу продления на стороне СмартЛомбард. Если функция онлайн продления не настроена или не разрешена для залогового билета, то вместо ссылки будет пустая строка.
ВАЖНО
Оплата клиентом не во всех случаях гарантирует проведение операции продления. - Тем не менее программа оповестит сотрудников в случае возникновения ошибок.
Good добавлено новое поле hiddenGood добавлено новое поле withdrawnGood удалено поле deletedonline_prolongation_urlGood добавлено описание полей: organization, subcategory, metal_name, metal_standart_nameGood добавлено описание поля sizebuyout_dateMerchant добавлено новое поле descriptionGood добавлено новое поле specificationsclient_surnameitem_type (1- товар, 2- имущество)hidden_reason добавили причину сокрытия "5 - на предпродажной подготовке"